% chapter Design of Elib
\chapter{Elib design} \label{chap:elib}
  The~{\it Elib} library is a $C\#$ asynchronous library for a remote control of e-Puck. 
  The~goal of the~library is to make developing programs for the~robot easier.
  This chapter presents several topics that influenced the~design of {\it Elib}.
  The~Examples on usage of $Epuck$ class and its interfaces are introduced is in Chapter~\ref{chap:usage}.

  In the~first place the~possibilities of programming e-Puck robot are depicted.
  Next section covers the~advantages and the~drawbacks of asynchronous remote control.
  Furthermore, key features of {\it Elib} are presented together with crucial decisions that
  lead to properties of {\it Elib}. 
  {\it Elib's} features are confronted with the~alternatives. The~differences are discussed
  and the~main reasons for choosing the~current implementations are mentioned.

  After that, the~logic of the~main classes $Sercom$ and $Epuck$ are introduced. Sections 
  \ref{sec:sercom} and \ref{sec:epuck} describe implementation of the~classes in detail. 
  In the~part devoted to $Sercom$ the~main stress is on the~design of Bluetooth communication processing.
  The~implementation details of the~two $Epuck's$ interfaces are the~main topic of the rest of this chapter. 

  The~last Section \ref{sec:suminterface} sums up qualities of interfaces 
  implemented by $Epuck$ and $Sercom$ class.
  Section \ref{sec:suminterface} also describes {\it Elib's} performance results.

  This chapter assumes that a reader understands the~use of callbacks 
  and $EventWaitHandle$ class in .Net.
  However, the~callbacks and $EventWaitHandle$ class together with other advanced .Net features 
  are introduced in section~\ref{sec:net}.

\section{Approaches to e-Puck programming} \label{sec:approach}
  E-Puck is distributed with several programs in its flash memory. 
  Most of the~programs implement a simple behaviour which introduces e-Puck sensors and actuators.
  There is a behaviour that makes e-Puck go to the~source of light.
  If another behaviour is running, e-Puck
  reacts to clapping and it turns around to the source of a clap. 
%  For example one of the~behaviours makes e-Puck cry, if it is falling.
   
  The~{\it BTCom} program and e-Puck bootloader are also distributed on e-Puck, but belong to different classes of programs. 
  The~bootloader allows users to change programs stored on e-Puck and
  {\it BTCom} allows e-Puck to communicate with other devices via Bluetooth
  
  The BTCom protocol works in two modes. The~text mode accepts commands for
  all sensors and actuators except for a command that requests a~picture 
  from e-Puck's camera. 
  In the~text mode the~accepted commands and replies of BTCom protocol are short text messages,
  but the picture can not be transferred from e-Puck.
  If {\it BTCom} runs in the~binary mode, 
  single byte commands are accepted instead of text messages.

  The~binary mode is more economical, 
  because the~commands are sent in single bytes and also the~integer values from sensors
  are not converted to a textual form.
  Unfortunately, the~binary mode of {\it BTCom} does not control all sensors and actuators, 
  because it accepts fewer commands than in the~text mode.
  The~absence of commands for controlling some sensors and actuators is the~main reason 
  for sending all commands from {\it Elib} to {\it BTCom} in the~textual form. 
  The~single exception is sending an image back to {\it Elib} in the~binary mode.
   
  Bootloader, officially called Tiny Bootloader\cite{tiny},
  is the~only wired program on e-Puck. It downloads other programs to e-Puck via Bluetooth. 
  Tiny Bootloader has its counterpart, a graphical PC application,
  which allows users to download hex files to e-Puck.
  A hex file\footnote{\small{\url{http://en.wikipedia.org/wiki/Hex_file}}} 
  for e-Puck is compiled C program for e-Puck's dsPic microchip. 
   
  All mentioned programs including Tiny Bootloader use a C library that interfaces the~devices on e-Puck. 
  The~library and the~programs are published under open source licence at
  \url{http://www.e-puck.org}.

  \subsection*{How to run a program} % (fold)
  If e-Puck is turned on, e-Puck starts running one of the~downloaded programs 
  according to its selector position\footnote{ E-Puck's selector switch is located on the~main board of e-Puck.}. 
  If a programmer wants to run another program, he has to switch selector to another position
  and hold a  reset button fo a second on e-Puck. Selected program is loaded from flash memory
  to RAM memory and immediately executed.	
   
  Suppose there is correct C code for e-Puck's processor saved on PC. What has to be done to run the~program?
  Let us describe the~procedure.
  Firstly it has to be compiled and linked. After that, a~transformation to a hex file is necessary,
  because e-Puck's dsPic is 16 bit processor. In the~next step Bluetooth and e-Puck are turned on. 
  The~robot and your computer are paired together. The~user has to enter the~PIN, 
  which is needed to pair the~devices. 
  PIN is a number, which is on e-Puck's body.
  The~OS opens a serial port for Bluetooth communication.
  Graphical counter part of Tiny Bootloader is needed. It is used to select the~hex file and choose the~opened port. 
  Furthermore, the~Tiny Bootloader guides user through the~downloading of the~hex file.
  The~instructions tell the~user to press a reset button on e-Puck. It has to be pressed only for about a second.
  Tiny Bootloader announces when the~download finishes. To run the~program it is necessary to reset the e-Puck.
   
  The~program is written to e-Puck's flash memory according to e-Puck's selector position.
  If another program had been saved under the~same selector position, it is overwritten by the~new program.
  Downloading  hex file to an e-Puck lasts approximately 30 seconds and it is sometimes unsuccessful. 
  Programming e-Puck via Tiny Boatloader is not very comfortable. 
  Luckily, there is an another way, which uses {\it BTCom} program downloaded on e-Puck. 

  In order to use {\it BTCom} turn e-Puck's selector to position, under which it is stored, and press reset button.
  Now {\it BTCom} is running.  Pair your PC with e-Puck as described above and use the~open port
  to control e-Puck.
  {\it BTCom} starts running in text mode, so its possible to use a terminal to communicate with e-Puck.
  E.g Hyperterminal on Windows. On Linux write directly to the~serial port using a command line.
  A program can control e-Puck via BTCom protocol too, but it must process the~commands and their replies.
   

  \begin{figure}[!hbp]
  \centering
  \ifpdf
    \includegraphics{epuck_monitor.pdf}
  \else
    \includegraphics[width=0.75\textwidth]{epuck_monitor}
  \fi
  \caption{\label{pic:monitor}%
   Epuck Monitor 2.0}
  \end{figure}

  Nice example of accessing sensors and actuators over Bluetooth is 
  e-Puck Monitor\footnote{\small{Download E-Puck Monitor from \url{http://www.e-puck.org}.}}.
  E-Puck Monitor is an open source graphical application written in C++, 
  which uses BTCom protocol. Its User Interface presents values of all e-Puck's 
  sensors in one window and user can easily control e-Puck's actuators.
  E-puck Monitor's serious drawback is its freezing. The~application does not respond, 
  because it waits synchronously to answers from {\it BTCom}.
  If a Bluetooth connection with e-Puck is broken or the~answer is lost, 
  the~application remains unresponsive.

  \subsection*{Summary} % (fold)
  Downloading a hex file to e-Puck's microchip and remote control over BTCom protocol 
  are two alternatives of controlling e-Puck.
  Using {\it BTCom}, a user does not have to download any file to e-Puck's microchip.
  It is great advantage, because the~length of developing cycle of program for e-Puck is reduced.
  The~developing cycle consist of:
  \begin{itemize}
    \item writing a code,
    \item compiling it,
    \item downloading it,
    \item debugging it,  
    \item and correcting it.
  \end{itemize}
  In following section the~advantages of remote control will be described in detail.

\section{Advantages of remote control} \label{sec:remote}
  Applications, which use {\it BTCom} and its protocol, run a whole algorithm on PC and {\it BTCom} just 
  executes the~commands and gets the~values from sensors. {\it Elib} library processes the~commands
  and their replies. A program for controlling e-Puck can use {\it Elib} and just ask
  the~library for sensor values or give a command to e-Puck. 
  Important is that download part is missing.
   
  Leaving out the item "downloading the program to e-Puck" from the life cycle in List above saves programmer 
  20 seconds or more, because the process of downloading a program to e-Puck is unreliable.
  Last but not least the quality of debugging is significantly improved by using a library for remote control.

  If a program is downloaded to e-Puck, there are only e-Puck's actuators for a feedback.
  The~actuators are a very poor debugging tool, because if something goes wrong, 
  it is impossible to say whether the~program stopped running,
  or e-Puck is waiting to sensors values, or battery is down. 
  Discovering the~problem, even if it is the~low battery, takes one or two loops of downloading and compiling the~program.
  E-Puck has an~indicator of low battery, but it is not reliable.
  Downloading a program takes a long time and successful download could last even a couple of minutes. 
  It drives a lot of people crazy.
   
  A programmer that controls a robot remotely can debug with tools of his programming environment and he still controls e-Puck.
  All this can be utilised, because a computer has much more resources than e-Puck.

  Let us mentioned a~few  techniques for debugging. 
  Logging of robot actions is often underestimated,
  but it is very useful for performance testing. 
  Flow control by setting breakpoints is the great advantage
  of remote control. However, in applications, which call procedures asynchronously, 
  the~ breakpoints should be set carefully.
  Breakpoints do not stop the asynchronous operation and do stop the main thread.
  Therefore breakpoints should be set only in place, 
  where no asynchronous methods have been invoked with timeout
  or the methods have been already finished.
  
  Another point of view is where the computation is performed.
  If the~remote control is used, it can be said that the~intelligence 
  is located on a computer. However if you load a program to e-Puck via Tiny Bootloader the~whole algorithm
  runs on e-Puck.
  The~resources of PC are also useful for a computation of the~program and not only for
  its debugging. E-Puck for example takes pictures smaller than 3200 bytes and still complicated image processing 
  requires too much work for e-Puck's microchip. It is faster to process the~picture
  on a computer. 
  Let us note that also implementing a genetic algorithm in 8 kB memory
  is very difficult.

\section{Design of the {\it BTCom} program. What does it mean for {\it Elib}?}
  \label{sec:btcomdesign}
  The~interfaces of {\it Elib} is designed for {\it BTCom} version 1.1.3, but {\it Elib} is also compatible with {\it BTCom} 2.0.
  The~complete {\it BTCom} source code version 2.0 is located on enclosed CD in file "btcom.c".

  {\it BTCom} is a mainly textual protocol, which is defined by {\it BTCom} program. The~answer of {\it BTCom} always begins 
  with the~first letter of the~relevant command.
  If the~command requires some sensor values, the~value is appended to the letter and
  sent. Otherwise the~first letter of a command is sent back alone. Each answer ends by 
  $\backslash$r$\backslash$n escape sequence.
  See below the~list of all text commands printed from {\it BTCom} below.
  \lstset{basicstyle=\small}
\begin{lstlisting}
"A"         Accelerometer
"B,#"       Body led 0=off 1=on 2=inverse
"C"         Selector position
"D,#,#"     Set motor speed left,right
"E"         Get motor speed left,right
"F,#"       Front led 0=off 1=on 2=inverse
"G"         IR receiver
"H"          Help
"I"         Get camera parameter
"J,#,#,#,#" Set camera parameter mode,width,heigth,zoom(1,4,8)
"K"         Calibrate proximity sensors
"L,#,#"     Led number,0=off 1=on 2=inverse
"N"         Proximity
"O"         Light sensors
"P,#,#"     Set motor position left,right
"Q"         Get motor position left,right
"R"         Reset e-puck
"S"         Stop e-puck and turn off leds
"T,#"       Play sound 1-5 else stop sound
"U"         Get microphone amplitude
"V"         Version of BTCom
\end{lstlisting}
    
  \subsection*{Two questions} % (fold)
  Let $A$ be a PC and $B$ be an e-Puck robot. $A$ controls $B$ over {\it BTCom} protocol. {\it BTCom} program located on $B$ 
  replies to all commands sent from $A$.
  The~answers of {\it BTCom} from $B$ allows $A$ to know that the~sent command was received and
  executed. 
   
  Two main questions which affect design of {\it Elib} arise from the~{\it BTCom} structure.
  Should {\it Elib} limit the~waiting time for an answer from $B$?
  How fast should {\it Elib} allow $A$ sending the~commands to $B$?
  \begin{remark}
  Sending commands from {\it Elib} in the~following paragraphs does mean 
  sending textual or binary commands
  using {\it BTCom}. It does not mean calling any functions of the~{\it Elib} library, which wrap the~sending. 
  \end{remark}
   
  It is necessary to understand, that not only executing a {\it BTCom} command, 
  but also a transfer of a command and a transfer of a reply take significant amount of time. 
  The~time is measured from a computer processor's point of view, because
  it is the~processor that is waiting for serial port until the~message is sent.
   
  Back to the~question how should {\it Elib} limit sending of the~commands.
  As we have said, sending commands takes a while and therefore sending is performed asynchronously. 
  Due to asynchronous sending, users do not have to wait to the~end of sending previous command and
  can send next one before the~first command has finished.
  It leads to queueing the~commands in a serial port output buffer of PC. Unfortunately the~buffer is usually not 
  very large and can easily overflow. 
  This is the~reason for implementation {\it Elib's} buffer, a queue, which slows down the~sending and does not allow
  overwriting of sent commands by each other in the~output buffer. 
   
  Is the problem with sending solved? Not for e-Puck. If the~commands were sent too fast,
  the~input buffer of e-Puck would have the~same problem, because e-Puck's processor does not keep up emptying e-Puck's
  input buffer. The~buffer would be flooded and the~commands would be overwritten. 
  {\it Elib} has to check, if the~Bluetooth is not able to send commands too fast for e-Puck
  and possibly slow down sending of commands even more.

  %How fast can e-Puck receive commands? Experiments showed, that gaps between commands around 0.02 s are 
  %critical at best condition, because e-Puck processes each answer immediately as it picks it up from its input buffer.
  \subsection*{How long {\it Elib} should wait for the answer of a sent command?} 
  Clearly we have to wait more than is the~minimum transfer time from a computer to e-Puck and back.
  The~transfer time depends on  amount of transfered data. 
  Sensors messages carry more data on the~way back, therefore sending sensors answers takes longer time.
  An extreme is a command for taking a picture. Sending command to e-Puck last about 0.02 s, but
  the~answer needs more than 0.2 s for a transfer.
   
  As we mentioned, waiting for the~answers takes even longer time than sending a command,
  so the~waiting is performed in {\it Elib} asynchronously too.
   
  Possible variability of waiting time force {\it Elib} to let the~user decide how long
   {\it Elib} should wait for an answer. The~{\it Elib} library does not limit the~minimum waiting time too,
  because the~convenient values differ according to the state of a battery on e-Puck, a strength of Bluetooth signal
  and so on. 
  
  \begin{definition}[Timeout]
  The~waiting times for answers are in {\it Elib} called $timeouts$.
  In examples, which are introduced in Chapter~\ref{chap:usage}, the~waiting times are set to values
  that allow commands to be confirmed without problems under good conditions.
  \end{definition}
  
  \subsection*{summary} % (fold)
  Let us sum up the~facts. Sending of commands takes significant amount of time.
  Sent commands are queued, because otherwise they could be overwritten in the~buffers.
  Receiving an answer takes even more time than sending a command from computer.
  We concluded to implement sending commands and receiving answers asynchronously, because the~communication with e-Puck
  can pointlessly block the~processor of the~host PC.

\section{Asynchronous programming model (APM)\\ for the~{\it Elib} library}
  \label{sec:apm}
  It was already mentioned that an asynchronous call of a function is convenient if the
  classical synchronous call let the~processor waiting for instance to a device.
  In e-Puck's case the~device is serial port. 
   
  Epuck Monitor \footnote{\small{Download at \url{http://www.gctronic.com/files/e-puckMonitor_2.0_code.rar}}}
  mentioned above implements synchronous communication with e-Puck using {\it BTCom}.
  Synchronous communication leads to freezing of Epuck Monitor. 

  On the~other hand, asynchronous programming is much more complicated than synchronous programming.
  The~goal of {\it Elib} is to hide the~complications of APM and offer an interface
  which performs sending and receiving messages asynchronously and
  which allows a programmer to easily create applications for e-Puck. 
%  For example applications like Epuck Monitor.
  What means asynchronous implementation in case of {\it Elib}? What is done if the~answer arrives in time
  and what if not? These questions are answered in the~next section called Asynchronous programming model for {\it Elib}.

  \begin{remark}[Callbacks]
  Callbacks are functions, which are called after some procedure has finished.
  \end{remark}
  {\it Elib} contains two main classes and it implements two interfaces through them.
  \begin{itemize}
    \item $Sercom$: public class, wraps serial communication.
    \begin{itemize}
      \item Implements -- $Write(..)$ function with arguments:
      \begin{itemize}
        \item string command -- specifies a type of sending command
        \item an integer -- the~$timeout$ for the command
        \item $Okf$ callback -- function called if the~answer is delivered in time.
        \item $Kof$ callback -- function called if the~$timeout$ has elapsed and the~answer did not arrive
        \item class object -- instance used to pass custom information to $Okf$ callback
      \end{itemize}
      \item Usage of $Write(..)$ function = "$Sercom's$ basic interface"
    \end{itemize}
    \item $Epuck$: presents an instance of a e-Puck robot, uses $Sercom$ internally.
    \begin{itemize}
      \item $Epuck's$ basic interface 
      \begin{itemize}
        \item Based on $Sercom's$ $Write(..)$ function 
        \item It  pass string argument for each command implicitly to $Write(..)$ function
      \end{itemize}
      \item Implements $IAsyncResult$ interface
      \begin{itemize}
        \item .Net interface
        \item It uses $Epuck's$ basic interface
      \end{itemize}
    \end{itemize}
  \end{itemize}

%  $IAsyncResult$ interface also accepts $timeout$, an instance of $object$ class and one callback, but it returns 
%  an implementation of $IAsyncResult$ interface which will be introduced later.
%  Simpler interface logic and the~fact that $IAsyncResult$ is broadly used interface
%  are reasons for its implementation.
  %The~interface is used across different .Net libraries.

\section{The~$Sercom$ class}\label{sec:sercom}
  An instance of $Sercom$ allows a computer to asynchronously communicate with other devices
  over serial communication. The~class accepts textual commands and parses textual answers.
  The~commands and answers can be distinguished according to its first letter.
  Let us describe its structure.
 
  \begin{definition}
  $Sercom$ waits after each sent command until the~ answer arrives or its $timeout$ elapses.
  Let us called this behaviour of waiting a $handshaking$.
  \end{definition}

  $Handshaking$ guarantees that the~commands would not be sent too fast,
  because $Sercom$ waits on e-Puck's answer. E-Puck picks up the~command from its input buffer and then sends the~reply.
  The~short answers under good conditions do not slow down sending with $handshaking$, because
  they arrive under 0.04 s. 
 

  At the~beginning of an {\it Elib's} development we thought about implementing both the~$handshaking$
  and the~$nonhandshaking$ sending.
  The~$nonhandshaking$ sending does not wait for answer of the~previous command. It sends the~next command immediately. 
  Motivation for $nonhandshaking$ is to save time which is spent on waiting for the~answers of the~sent commands.
  Consequently, $nonhandshaking$ has to ensure that the~input buffer does not overflow.
  We have experienced that it is a non-trivial task to set the~correct time gap after different types of commands. 
  The~final observation is that the~$nonhandshaking$ sending is even slower than the~$handshaking$ sending, 
  because the~gaps after sent commands have to be set at maximum in order to avoid a failure under all conditions. 
  The~gaps in $nonhandshaking$ mode has too be unnecessarily large, 
  because it must not let the~input buffer of e-Puck overflow.

  $Handshaking$ solves the~problem with synchronising sending 
    and receiving the~commands and their answers. 
  It made us choose $handshaking$ as the~best implementation.

  E-Puck processes a received message in three steps. It picks the~command from input buffer.
  It executes the~command and then replies with an answer.
  For commands with long sending or executing phase it means the following consequence.
  If such command is sent, next commands has to wait longer time, because there is a
  danger of e-Puck's input buffer overflow.

  Next advantage of $handshaking$ is its simple and elegant implementation. It also does not depend on {\it BTCom} implementation so much.
  If {\it BTCom} had improved the~times of executing the commands
  in $nonhandshaking$ mode it would have resulted into a change of a table that stores minimal gaps after each command.

 \subsection{The~logical problems with a confirmation}\label{sec:logical}
  In $nonhandshaking$ mode a lot of commands can be sent before the~$timeout$ of the~first elapses.
  Let us introduce a common situation, which causes a serious problem. 
  
  Let us suppose, that {\it Elib} library has to send a lot of commands of one type.
  For example all the~commands can control the~front LED light.	
  The~problem consists of unwanted postponing a call of the~$Kof$ callback. 
  Let us imagine that the~answer for the~first command
  is lost, but the~second answer manage to be processed under $timeout$ of the~first command.
  It means that $Okf$ callback is called and the~user assumes that everything is fine for the first command.
  Furthermore, the~problem can be postponed to the~last command of the~same type,
  because the~reply to the~second command can replace the~reply of the~third command
  and so on.

  The~commands can be logically different, although they are of the~same type.
  The~$Kof$ callback can be called on a different command, because the~first command can turn the~front LED on 
  with message "F,1", however the~last command can switch the~front led off with "F,0" command and 
  the~reply to both commands is "F$\backslash r\backslash n$. The reason is that $BTCom$ replies to commands without
  their arguments.

  $Handshake$ mode does not suffer from calling the~wrong callback. 

  \begin{example}
  Let us imagine a situation where a user of Elib receives a $Kof$ callback for "SetSpeed(0.5,0.5)" command.
  He decides to stop with the same command "SetSpeed(0,0)". He successfully receives the $Okf$ callback.
  Unfortunately, the user does not know if the callback confirms "SetSpeed(0.5,0.5)" or "SetSpeed(0,0)".
  \end{example}
  The~ simple solution is to paste a command of a different type which prevents interchanging of the~answers.

\begin{figure}[!hbp]
\begin{lstlisting}[language=cs]
public class Sercom {
  public void Write(string command, RCallback okf, NRCallback kof,object state, double timeout) {
          //... the body of function
  }
}
public class Epuck {
  public void Stop(OkfActuators okf, NRCallback kof, object state, double timeout) {
          //example of interface directly based on BTCom's interface
  }
  public IAsyncResult BeginStop(double timeout, AsyncCallback callback, Object state) {
          //example of IAsyncResult interface implementation
  }
}
\end{lstlisting}
\caption{Public methods of $Sercom$ and $Epuck$} \label{serep}
\end{figure}

\subsection{$Sercom's$ inner implementation}\label{sec:versions}
  The~current $Sercom's$ implementation has only four public functions.
  The~constructor, the~$Start$ method, the~$Dispose$ method and the~public method $Write$. 
  See its interface in Figure~\ref{serep}.	

  The~previous versions of {\it Elib} in addition have implemented public 
  method for changing from $nonhandshake$ mode to 
  $handshake$ mode and vice versa.
  The~implementation of~$nonhandshaking$ mode used one 
  thread for each unconfirmed command in handshaking mode.
  It lead to instability of a program, if the Bluetooth communication breaked up.
  
\subsection*{Previous version}\label{previous}
  %\input{sercom_nohandshake.TpX}
  \begin{figure}[!hbp]
  \centering
  \ifpdf
    \setlength{\unitlength}{1bp}%
    \begin{picture}(319.36, 236.63)(0,0)
    \put(0,0){\includegraphics{sercom_nohandshake.pdf}}
    \put(41.75,105.11){\fontsize{5.30}{6.36}\selectfont These methods work}
    \put(41.75,95.11){\fontsize{5.30}{6.36}\selectfont with Serial Port.}
    \put(153.42,153.66){\fontsize{8.83}{10.60}\selectfont notSended}
    \put(153.42,207.34){\fontsize{8.83}{10.60}\selectfont notSended}
    \put(63.66,207.34){\fontsize{8.83}{10.60}\selectfont notSended}
    \put(60.73,61.89){\fontsize{8.83}{10.60}\selectfont ~Receive(..)}
    \put(60.73,38.33){\fontsize{8.83}{10.60}\selectfont \textcolor[rgb]{1, 0, 0}{hReceive(..)}}
    \put(66.10,154.40){\fontsize{8.83}{10.60}\selectfont ~Send(..)}
    \put(66.10,133.67){\fontsize{8.83}{10.60}\selectfont \textcolor[rgb]{1, 0, 0}{hSend(..)}}
    \put(237.00,207.20){\fontsize{7.80}{7.60}\selectfont public Write(..)}
    \put(227.20,89.27){\fontsize{8.83}{10.60}\selectfont Checker.Okf(..)}
    \put(227.20,110.39){\fontsize{8.83}{10.60}\selectfont Checker.Kof(..)}
    \put(155.29,100.33){\fontsize{8.83}{10.60}\selectfont ~Sent [c]}
    \put(161.97,74.11){\fontsize{8.83}{10.60}\selectfont \textcolor[rgb]{1, 0, 0}{hSent}}
    \end{picture}%
  \else
    \setlength{\unitlength}{1bp}%
    \begin{picture}(319.36, 236.63)(0,0)
    \put(0,0){\includegraphics{sercom_nohandshake}}
    \put(41.75,105.11){\fontsize{5.30}{6.36}\selectfont These methods work}
    \put(41.75,95.11){\fontsize{5.30}{6.36}\selectfont with Serial Port.}
    \put(153.42,153.66){\fontsize{8.83}{10.60}\selectfont notSended}
    \put(153.42,207.34){\fontsize{8.83}{10.60}\selectfont notSended}
    \put(63.66,207.34){\fontsize{8.83}{10.60}\selectfont notSended}
    \put(60.73,61.89){\fontsize{8.83}{10.60}\selectfont ~Receive(..)}
    \put(60.73,38.33){\fontsize{8.83}{10.60}\selectfont \textcolor[rgb]{1, 0, 0}{hReceive(..)}}
    \put(66.10,154.40){\fontsize{8.83}{10.60}\selectfont ~Send(..)}
    \put(66.10,133.67){\fontsize{8.83}{10.60}\selectfont \textcolor[rgb]{1, 0, 0}{hSend(..)}}
    \put(237.00,207.20){\fontsize{7.80}{7.60}\selectfont public Write(..)}
    \put(227.20,89.27){\fontsize{8.83}{10.60}\selectfont Checker.Okf(..)}
    \put(227.20,110.39){\fontsize{8.83}{10.60}\selectfont Checker.Kof(..)}
    \put(155.29,100.33){\fontsize{8.83}{10.60}\selectfont ~Sent [c]}
    \put(161.97,74.11){\fontsize{8.83}{10.60}\selectfont \textcolor[rgb]{1, 0, 0}{hSent}}
    \end{picture}%
  \fi
  \caption{\label{pic:sercom_nohandshake}%
   Old structure}
  \end{figure}
  In  Figure~\ref{pic:sercom_nohandshake} the~schema of the~inner implementation 
  from the~previous versions of {\it Elib} is illustrated.
  It shows functions and objects, which were used for sending and receiving the~messages.
  Some methods have $nonhandshaking$ and $handshaking$ versions.
  $Nonhadshaking$ methods, which are drawn in red	in Figure~\ref{pic:sercom_nohandshake}, implement the~same logic 
  as $handshaking$ methods except they allow to send and receive more commands
  at once.



%  Sending a command starts with calling public method $Write$. The~instance of $checker$ class is created in the~$Write$ method.
%  $Checker$ stores the~command name, $Okf$, $Kof$, a reference to $state$ object and references to $notSent$ 
%  and $Sent$ queues.
%  It also stores a boolean value $answered$, which indicates whether the~answer has been already delivered or not.
%
%  $Checker$ starts a separate thread in the~$Write$ method. In the~thread runs the~$check$ method, which at first sleeps for a $timeout$.
%  After the~$timeout$ expires a method the~$check$ method finds out whether the~answer has arrived.
%  If $answered$ has been set to true, it means that the~$Okf$ callback has already been 
%  called and nothing is done. In other case, $Kof$ is called and $answered$ is set to $true$.
%
%  Let us introduce methods which send and receive commands.
%  $Send$ respectively  the~$hSent$ method and $Receive$ respectively the~$hReceivve$ method run in a worker thread. 
%  Method $hSent$ dequeues an instance of $checker$ class from $notSent$ queue and
%  sends the~command as soon as possible. The~$hSent$ method waits until the~$hSent$ variable
%  of previous command is set to $null$. Both methods move the~instance
%  of $checker$ class from $notSent$ to $Sent$ respectively to $hSent$ after sending the~command.
%
%  $Sent$ is a queue of the~$checker$ objects, $hSent$ is a reference to the~$checker$ object. 
%  
%  \label{p:oneargument}
%  The~$Receive$ method process the~text messages from the~serial port and if a whole command is received
%  it finds the~first relevant instance of  $checker$.
%  The~answer is passed as one of the~arguments to $Okf$ function and the~function is called.
%  If there is no $checker$ instance, which carries the~same type of command with received answer,
%  the~answer is thrown away.
%
%  $Okf$ delegate for the~functions has additional string arguments for the~answer, because the~sensors answers contain values
%  which the~functions use after they are called.
%  $Kof$ function has nothing to process, therefore it implements only the~$state$ argument 
%  which is also available in $Okf$ functions. The~$state$ argument serves to retrieving
%  some other information from the~callback functions, although it can be also used for
%  passing the~information through the~$state$ object into the~callback method.
%
%  The~$checker$ instance of each sent command is during its existence saved either in the~$notSent$
%  queue or in the~$Sent$ queue, respectively in the~$hSent$ variable.
%  After calling the~$Okf$ or the~$Kof$ functions the~$checker$ instance is removed either from $notSent$ queue
%  or from $Sent$ queue, respectively from $hSent$ variable. 
%
%  This design cumulates threads. For each command in $notSent$ queue there is 
%  one thread sleeping in $check$ method. If the~sending is slow, the~commands and its $checker$ objects are queued in
%  $notSent$ together with their sleeping threads. Threads are valuable system resources. 
%
%  It can be sent and received more than 20 commands per second and the~longest $timeout$ for 
%  e-Puck reset has to be at least 1.5 second, so more than 30 commands can be easily created.
%  If the~{\it Elib} is used improperly, for example thousand of commands are sent and its $timeout$ elapses
%  in the~same time, then thousand of threads is need. This design of {\it Elib} is inconvenient, because
%  it uses abundant number of system resources.

\subsection*{The~current $Sercom$}\label{sec:current}
  The~current version abandoned the~implementation of the~$nonhandshaking$ mode, 
  because of the~problems with receiving answers described 
  in Section~\ref{sec:approach}.
  It also solves the~problem with	redundant threads. 

  \subsubsection*{Inner structure} % (fold)
  %\input{sercom_handshake.TpX}
  \begin{figure}[!hbp]
  \centering
  \ifpdf
    \setlength{\unitlength}{1bp}%
    \begin{picture}(319.35, 257.75)(0,0)
    \put(0,0){\includegraphics{sercom_handshake.pdf}}
    \put(117.44,49.67){\fontsize{7.07}{8.48}\selectfont binaryModeRead(..)}
    \put(117.44,76.07){\fontsize{7.07}{8.48}\selectfont textModeRead(..)}
    \put(127.02,220.54){\fontsize{8.83}{10.60}\selectfont notSent}
    \put(225.68,59.49){\fontsize{8.83}{10.60}\selectfont hshake\symbol{95}sent}
%    \put(108.63,115.68){\fontsize{5.30}{6.36}\selectfont These methods work with Serial Port.}
    \put(108.63,135.68){\fontsize{5.30}{6.36}\selectfont These methods work}
    \put(108.63,125.68){\fontsize{5.30}{6.36}\selectfont with Serial Port.}
    \put(26.79,59.35){\fontsize{8.83}{10.60}\selectfont Read(..)}
    \put(117.44,164.96){\fontsize{8.83}{10.60}\selectfont AsyncSend(..)}
    \put(26.79,164.96){\fontsize{8.83}{10.60}\selectfont Send(..)}
    \put(228.32,147.36){\fontsize{8.83}{10.60}\selectfont callKof(..)}
    \put(228.32,129.76){\fontsize{8.83}{10.60}\selectfont callOkf(..)}
    \put(228.14,86.63){\fontsize{8.83}{10.60}\selectfont checkSD(..)}
    \put(228.32,220.40){\fontsize{8.83}{10.60}\selectfont CheckNS(..)}
    \put(24.79,220.40){\fontsize{8.80}{9.60}\selectfont public Write(..)}
    \end{picture}%
  \else
    \setlength{\unitlength}{1bp}%
    \begin{picture}(319.35, 257.75)(0,0)
    \put(0,0){\includegraphics{sercom_handshake}}
    \put(117.44,49.67){\fontsize{7.07}{8.48}\selectfont binaryModeRead(..)}
    \put(117.44,76.07){\fontsize{7.07}{8.48}\selectfont textModeRead(..)}
    \put(127.02,220.54){\fontsize{8.83}{10.60}\selectfont notSent}
    \put(225.68,59.49){\fontsize{8.83}{10.60}\selectfont hshake\symbol{95}sent}
%    \put(108.63,115.68){\fontsize{5.30}{6.36}\selectfont These methods work with Serial Port.}
    \put(108.63,135.68){\fontsize{5.30}{6.36}\selectfont These methods work}
    \put(108.63,125.68){\fontsize{5.30}{6.36}\selectfont with Serial Port.}
    \put(26.79,59.35){\fontsize{8.83}{10.60}\selectfont Read(..)}
    \put(117.44,164.96){\fontsize{8.83}{10.60}\selectfont AsyncSend(..)}
    \put(26.79,164.96){\fontsize{8.83}{10.60}\selectfont Send(..)}
    \put(228.32,147.36){\fontsize{8.83}{10.60}\selectfont callKof(..)}
    \put(228.32,129.76){\fontsize{8.83}{10.60}\selectfont callOkf(..)}
    \put(228.14,86.63){\fontsize{8.83}{10.60}\selectfont checkSD(..)}
    \put(228.32,220.40){\fontsize{8.83}{10.60}\selectfont CheckNS(..)}
    \put(24.79,220.40){\fontsize{8.80}{9.60}\selectfont public Write(..)}
    \end{picture}%
  \fi
  \caption{\label{pic:sercom_handshake}
   Methods for changing state of $ansGuard$ instance}
  \end{figure}

  {\it Elib} currently uses two working threads and implements only the~$handshake$ mode.
  One thread running in the~$checkNS$ function checks whether the~$timeout$ of sent commands
  has not elapsed during waiting in $notSent$ queue. The~second thread checks whether the~sent command
  stored in the~$hshake\_sent$ variable has a valid $timeout$ or the~$timeout$ has already elapsed.
  $Send$ calls asynchronously $AsyncSend$ function, which dequeues an instance of $ansGuard$ from $notSent$ queue.
  The~$ansGuard$ class is a wrapper of commands.
  The~answers are read asynchronously in the~$DataReceived$ procedure.
  \begin{remark}
  Both methods $Send$ and $DataReceived$ use a so called .Net asynchronous
  delegate invocation. It enables simple asynchronous invocation using a minimum resources.
  \end{remark}
  \begin{definition}[Delegate]
  Delegate\cite{delegate} is a .Net strictly typed wrapper for function instances.
  An example of asynchronous function invocation using .Net delegate is depicted in Figure~\ref{invocation}.
  \end{definition}
  \begin{remark}
  The $ThreadPool$ class, which is created at 
  start of the~application, prevents from useless thread creation. 
  The~instance of the~class keeps the~threads after~a~function termination.
  The~threads are handed over among different functions, which are called 
  by asynchronous delegate invocation.
  $ThreadPool$ uses a delegate to invoke the~functions in different threads.
  \end{remark}
  
\begin{figure}[!hbp]
\begin{lstlisting}[language=cs]
// The form of delegate declaration garantees, that only functions
// with no arguments and with void returning value 
// can be saved in SendAsync delegate.
delegate void SendAsync();
void Send(object Sender, EventArgs ev) {
  //SendAsyncCall is a function, asyncCaller a delegate variable
  SendAsync asyncCaller = new SendAsync(SendAsyncCall);
  asyncCaller.BeginInvoke(null, null);      
}
// This function match requirements of SendAsync delegate.
void SendAsyncCall(){
  //the body
}
\end{lstlisting}
\caption{Example of Asynchronous function invocation}\label{invocation}
\end{figure}

  All commands are wrapped by the~$ansGuard$ class. An instance of $ansGuard$ is created in the~$Write$ method.
  The~references of callbacks are stored in $ansGuard$ together with their $state$ argument.  
  The~$timeout$ value in seconds is added to the~current time and stored in $ansGuard$.
  The~instance of $ansGuard$ is immediately enqueued in the~$notSent$ queue.

  The~queue $notSent$ implements an event $NonEmpty$, which calls the~$Send$ method whenever something is written
  to $Sercom$ by the~$Write$ method. The~$Sent$ method is also called, if the~$hshake\_sent$ variable is set to $null$.
  $Send$ just calls $SendAsyncCall$. See a snippet in Figure~\ref{invocation} .

  The~$Read$ method which is called asynchronously just calls $textModeCall$
  in the~text mode and $binaryModeRead$ in the~binary mode.
  The~only command, which is sent in the~binary mode in {\it Elib}, is the~command to get a picture.
  The~picture is the~only binary answer of {\it BTCom} too.
  A description of $binaryModeRead$ is postponed after  
  introducing $textModeCall$ method.

  Does $SendAsyncCall$ implement $handshaking$ mode?
  $SendAsyncCall$ checks whether the~previous command is received by
  checking whether $hshake\_sent$ is set to $null$.
  If the command is received and the~$notSent$ queue contains some $ansGuard$, 
  then $SendAsyncCall$ moves $ansGuard$ from $notSent$ to $hshake\_sent$
  queue and sends the~command. 

  The~answers of $Sercom$ are processed in the~$Read$ function
  which is the~$DataReceived$ handler of .Net $SerialPort$. The~$DataReceived$ handler is called asynchronously
  in .Net implementation of the~$SerialPort$ class if at least one new character is delivered to
  serial port input buffer. 

  
  Every time the~$textModeCall$ is raised, the~new characters are step by step
  added to the~$ans$ container. If the~whole answer is stored in $ans$, $ans$ is cleared.
  The~found $answer$ is checked against $ansGuard$ stored in $hshake\_sent$.
  If it matches, the~$Okf$ callback is called and the~$hshake\_sent$ variable is set to $null$. 
  Also the~$Send$ function is called via the~$Received$ delegate. If the~answer does not match, it is thrown away. 
  
  If the~binary mode is on, the~$binaryModeRead$ procedure is called from
  the~$Read$ function. The~$binaryModeRead$ does not read bytes step by step.
  At first it reads first three bytes where width, height and mode of a picture is stored.
  The~total size of a picture is computed from the~first three bytes of the~picture.
  After receiving the~first three bytes the~function reads remaining bytes.
  If the~picture is transferred before the~$timeout$ elapsed, then the~$Okf$ callback is called.
  The~$Kof$ callback is called otherwise. 
  If $Sercom$ is receiving the~picture and the~time out elapses,
  $Sercom$ continues receiving the~picture. $Sercom$ stops the~receiving only if
  the~image is complete or if no bytes have been received longer than 0.1 seconds.
  The~$Kof$ callback of "GetImage" command is the~only $Kof$ callback 
  that can have the~answer at disposal, so the~picture is passed to $Kof$ callback too.	

  The {\it Elib} library receives image after $timeout$, because of implementation of~ $BTCom$,
  which can not receives command during sending a picture.
  After $Kof$ or $Okf$ call in binary mode instance of $ansGuard$ is removed from $hshake\_sent$ 
  and $Send$ method is invoked using $Received$ event.
  The~last action of $binaryModeRead$ is to switch the~flag from binary mode to text mode.
 
  \begin{remark}
  The~{\it BTCom} switches back to the~text mode automatically, because
  the~"GetImage" command is sent in binary mode to e-Puck together with an empty byte, which
  switches {\it BTCom} on e-Puck  immediately after sending the~picture back to the~text mode.
  \end{remark}

  Sending and receiving commands answers works well 
  until an answer is lost. $Timeouts$ ensure that the~stacked instance of $ansGuard$ are cleared after its $timeout$  elapses.
  The~instance of $ansGuard$ is stacked either in $notSent$ queue or in $hshake\_sent$.
  Both methods, which implement the~removal of an $ansGuard$, run in worker threads and also implement
  sophisticated system of waking and putting their threads to sleep, which prevents the~threads from wasting
  the~CPU time during their waiting to the~$timeout$ expiration. 
  The~$checkSD$ function looks after the~$ansGuard$ in $hshake\_sent$ and the~$checkNS$ function guards
  the~$ansGuards$ in the~$notSent$ queue.

  \begin{remark}
  For details of $Sercom$ implementation see the~code 
  and the~reference documentation in enclosed CD.
  \end{remark}
  
  \subsection{$Sercom's$ interface} % (fold)
  Let  us present the~interface of $Sercom$ and its public members.
  Figure \ref{publicser} lists all public functions of $Sercom$.
  The~$Write$ function can be used only
  after the~$Start$ function is called. The~$Start$ function is called only once and
  it opens serial port and initialise the~{\it BTCom} communication. 
  The~serial port is opened with parameters set in the~constructor of $Sercom$ or with
  default parameters specified in $Sercom$ in $Sercom's$ constants. The~$Dispose$ method closes the~serial port
  and prepares $Sercom$ for a garbage collection.

\begin{figure}[!hbp]
\begin{lstlisting}[language=cs]
public class Sercom:IDisposable{
  public void Write(string command, OkfCallback okf, KofCallback kof,object state, double timeout);
  public void Start();
  public Sercom(string portName, int serialPortWriteTimeout, int serialPortReadTimeout);
  public Sercom(string portName) : //with default constants
        this(portName, defWriteTimeout, defReadTimeout) { }
  public int NotAnswered{get;}
  public int NotSent{get;}
  public byte[] LastImgBytes{get;}
  public bool FullImgBytes{get:}
  public int ModeImg{ get:}
  public int HeightImg{ get;}
  public int WidthImg{ get;}
  public void Dispose();
}
\end{lstlisting}
\caption{Public functions of $Sercom$} \label{publicser}	
\end{figure}

  There are also several properties available. The~$NotAnswered$ and $NotSent$ properties
  show how much is the~instance $Sercom$ class occupied. $NotSent$ returns only the~length of the~$notSent$ queue. 
  $NotAnswered$ is at most by one greater than $NotSent$,
  because it returns number of $ansGuards$ in $notSent$ plus one if is an $ansGuard$ in $hshake\_sent$.

  The~remaining properties are attributes of the~last taken image. 
  They are valid, if the~$FullImgBytes$ is set to true.
  Otherwise the~properties do not have to be from the~last image.
  If the~$Okf$ was called on the~last taken image then $FullImgBytes$ is set to $true$. The~property
  comes in use if the~$Kof$ callback was called, because it can be called from $notSent$ queue  when the~bytes of image got lost, or the~image is all right, but it was received too late. 
  Width, height, mode and bytes are used as parameters for bitmap, 
  which is created in the~$Epuck$ class.

\section{The~$Epuck$ class} \label{sec:epuck}
  An instance of $Epuck$ offers a virtual representation of e-Puck,
  which interfaces all sensors and actuators of e-Puck to user. 
  The~$Epuck$ class also hides Bluetooth communication from the~user.

  $Epuck$ uses $Sercom$ internally and makes controlling of robot much more comfortable.
  $Sercom$ treats only the~command "GetImage" specially, because it is the~only one command 
  processed in binary mode
  and it has big time requirements. $Sercom$ does not differentiate between other commands.
  $Epuck$ differentiates between commands a lot. 
  It tights $Epuck$ with concrete implementation of {\it BTCom},
  but it also allows to process the~answers and to offer a typing of the~returning values, which increases
  applicability. Main goal of $Epuck$ class is to offer a good interface.

  In this chapter the~usage of $Sercom$ in $Epuck's$ class is presented together with additional methods 
  for implementation of the~interfaces. The~reasons, which lead to implementing two independent interfaces for
  controlling e-Puck robot through $Epuck$ class, are presented.
  Last but not the~least the~used technology of .Net is mentioned.

  The~$Epuck$ class brings nothing more than interface and debugging tools. We describe the~interface
  on examples as much as possible. There are several introductory examples in these chapter,
  which explain the~properties of the~interface. Furthermore, 
  guide lines for the~$Epuck$ class and the~debugging
  tools can be found in Chapter~\ref{chap:usage}.
  The~following sections present the~internals of $Epuck's$ methods.
  
\subsection{$Basic$ interface: $Okf$ and $Kof$ callbacks} \label{sec:okfkofi}
  $Epuck's$ basic interface just wraps the~$Sercom$ class. Methods of $Epuck's$ basic interface
  differ in callback parameters. Types of callbacks differ according commands, which
  were sent by functions of $Epuck's$ basic interface. 
  We divide callbacks and $Epuck's$ methods in following categories.
  \begin{itemize}
    \item Functions for actuators and sensors with string return values
    \item Functions for sensors returning array of integers
    \item Function for sensors returning an image 
  \end{itemize}
  commands for actuators, sensors with string return value and sensors, which return an array of integers.
  $Epuck$ treats pictures differently too, because it passes to callback a $Bitmap$ instance.


\begin{figure}[!hbp]
\begin{lstlisting}[language=cs]
public class Epuck{
  public void Stop(OkfActuators okf, NRCallback kof, object state, double timeout) {
          actuators(Commands.c_Stop(),okf,kof, state, timeout, "Stop(..)");
  }
  public void GetIR(IntSensorsOk okf, NRCallback kof, object state, double timeout) {
          IntArrSensors(Commands.c_Proximity(),8,okf,kof,state,timeout,"GetIR(..)");
  }
  public void GetBTComVersion(stringSensors(..)Ok okf, NRCallback kof, object state, double timeout) {
          stringSensors(..)(Commands.c_Version(), okf, kof, state, timeout, "BTComVersion(..)");
  }
  public void GetPicture(CamSensor okf, CamSensor kof, object state, double timeout) {
          checkArgs(okf, kof, timeout);
          logf(Action.call, f_name);
          ser.Write(Commands.c_GetImage(),
          (ans, data) => {
            okf(parsingBitmap(ser.LastImgBytes, ser.WidthImg, ser.HeightImg, ser.ModeImg), data);
            logf(Action.ok, f_name);
          },
          (data) => {
            if (ser.FullImgBytes)//a whole img was captured
              kof(parsingBitmap(ser.LastImgBytes, ser.WidthImg, ser.HeightImg, ser.ModeImg), data);
            else
              kof(null, data);//img is demaged
            logf(Action.ko, fname);
          },
          state,timeout);		
  }	   
}
\end{lstlisting}
\caption{Four types of $Epuck$ control functions}
\label{publicep}	
\end{figure}

  Although there are four kinds of commands, the~implementation differs only in processing the~answer.
  The~processing functions $actuators(..)$, $intArrSensors(..)$, $stringSensors(..)$ are all similar to $GetImage(..)$ method.
  
  There are only two differences between $GetImage(..)$ and other functions.
  Other functions have to parse their~answers in $Okf(..)$ functions differently and they do not parse
  answer in $Kof(..)$ callback at all.

  The~differences between $GetImage(..)$ and the~processing functions consist in using different
  delegates for $Okf(..)$ functions. All $Kof(..)$ functions fit to the same delegate $KofCallback$. 
  Only the~$GetImage(..)$ function defines its own delegate $OkfKofCamsSensor$, 
  which $GetImage(..)$ also uses for the~$Okf(..)$ functions.
  
  \begin{remark}
  As you can see in Figure~\ref{publicep} on lines 14-18 and 19-25,
  the~callbacks are wrapped in lambda functions \cite{lambda}.
  Instead of passing $Okf(..)$ and $Kof(..)$ directly to $Sercom.Write(..)$ function,
  $Okf(..)$ and $Kof(..)$  are called within the~lambda functions.
  The~lambda functions allow logging and parsing the~answers.
  \end{remark}

  A function $checkArgs$ on line 12 of $GetPicture(..)$ does not allow to pass invalid arguments
  to $Epuck$ functions. $Timeout$ has to be a positive $double$ value, $Okf$ and $Kof$ delegates 
  has to be defined and not set to $null$.

  $Okf(..)$ callbacks should be used for implementing the~desired algorithm.
  On the~other hand, $Kof(..)$ callbacks should perform repair actions in order to get into a valid state.
  Users of {\it Elib} should always have in mind,
  that $Kof(..)$ callbacks can be raised very often for low $timeouts$,
  but the~call of $Kof(..)$ callback signalizes a serious error state.
  See Section~\ref{sec:interfaces} for more examples of how to use $Okf(..)$ and $Kof(..)$ callbacks.


\subsection{The~$IAsyncResult$ interface} \label{sec:iasync}
  Two callbacks and a schizophrenic logic of the~$Okf(..)$ and $Kof(..)$ implementation are not
  convenient for exploring e-Puck's sensors and actuators, 
  however they allow e-Puck to easily recover from every situation.

\begin{figure}[!hbp]
\begin{lstlisting}[language=cs]
interface IAsyncResult{
  public Object AsyncState { get; }
  public Boolean CompletedSynchronously{get; } 
  public WaitHandle AsyncWaitHandle { get; }
  public Boolean IsCompleted { get; }
}
\end{lstlisting}
\caption{$IAsyncResult$ interface}
\label{interface}
\end{figure}

  Motivation for implementing the~$IAsyncResult$ is its clear usage and its proven usability.
  See Chapter~\ref{chap:usage} for $IAsyncResult$ introduction and examples.
  The~requirements of interface is shown in Figure~\ref{interface}

  See the~$IAsyncResult$ example in Figure~\ref{arexample}, which uses an instance
  of $Epuck$ to get IR sensor values from a real e-Puck. The~$timeout$ is the~only parameter of $BeginGetIR(..)$,
  which has nothing to do with $IAsyncResult$ interface.

\begin{figure}[!hbp]
\begin{lstlisting}[language=cs]
IAsyncResult ar = ada.BeginGetIR(timeout, callback, state);            
int[] IRSensors = ada.EndGetFtion(ar); //if callback == null
\end{lstlisting}
\caption{Usage of $IAsyncResult$}\label{arexample}
\end{figure}

  An asynchronous operation implemented by $IAsyncResult$ needs two functions. 
  The~first function usually starts with 
  "$Begin$" prefix and the~second starts with "$End$" prefix. 
  This convention is strictly respected in {\it Elib}.
  The function $BeginGetIR(..)$ is example of the~first function and $EndGetFtion(..)$ of the~second function.

  If the~$callback$ delegate is null, then we need the~$EndGetFtion(ar)$ function
  in order to be sure that the~real e-Puck has sent the~values of IR sensors. 
  See Figure~\ref{arexample}.
  The~call of $EndGetFtion(..)$ blocks the~current thread and waits synchronously until the~real
  e-Puck is stopped.

  If the~$callback$ functions are defined, they are raised after the~$BeginGetIR(..)$ function has finished.
  Usually, if $callback$ delegate is used, then the~$EndFtion(..)$ function call is not necessary.

  The~only possibility of $IAsyncResult$ interface to signal an error is raising an exception.
  The~exception is passed to callback or the~"End" function raises it.

  The~$ar$ instance of the $IAsyncResult$ interface allows the~$EndGetFtion(..)$ to wait to the~end of $BeginGetIR(..)$ function.
  The~instance is also used for passing user defined data in $state$ object to the~callback function,
  because $ar$ instance has an $ar.AsyncState$ reference to $state$ object.
  Another important feature of $ar$ is, that it allows $EndGetFtion$ function to receive the~data
  from $ar$. For example an integer array of IR sensors' values can be extracted from $ar$, which illustrates Figure~\ref{arexample}.
  
\subsection{$IAsyncResult$ implementation} \label{sec:iasyncimpl}
  Jeffrey Richter \cite{IAsync} made a nice example of two classes, which implement $IAsyncResult$ interface.
  I used his classes and modified them according to {\it Elib}'s needs.
  The~first class is $AsyncNoResult$ and implements $IAsyncResult$ for actuators.
  The~second class is generic $AsyncResult<T>$ subclass of $AsyncNoResult$. 
  It implements $IAsyncResult$ interface for sensors.
  \begin{definition}[Generic class]
  Generic class $C<T>$ with type $T$ means, that the~type  $T$ is chosen at compile time. 
  \end{definition}
  Instances of $AsyncResult<T>$ are used
  for $String$, $Bitmap$ as well as integer array answers with a different generic parameter $T$.
    

  
  The~idea of the~$IAsyncResult$ interface is that a programmer does not have to know which
  class implements the~$IAsyncResult$. They use $IAsyncResult$ type in a code. See Figure~\ref{arexample}. 
  On the~other hand, the~functions $BeginGetIR$ and $EndGetFtion$ have to know the~type, which is passed to $IAsyncResult$ object.
  "Begin" function in {\it Elib} creates the~instances $AsyncNoResult$ for actuators and $AsyncResults<T>$ for sensors.
  "End" functions in {\it Elib} wait until the~end of "Begin" functions and 
  throw exceptions if the~commands have not been delivered in time.
  If the~answer is delivered in time and if the~command has requested a sensor value, 
  the~"End" function returns the~desired sensor's values.
  
\subsection*{Obligatory members of $IAsyncResult$} \label{sec:iasyncmemb}
  Let us examine in detail the~$IAsyncResult$ interface from Figure~\ref{interface}. 
  \begin{itemize}
  \item $AsyncState$ is an object used as argument for a callback function, which
  is passed to "Begin" function. If no callback is passed, the~$AsyncState$ is not used. 
  $AsyncState$ is useful for passing information to the~callback.
  \item $AsyncWaitHandle$ is a synchronisation primitive which allows waiting until the~operation 
  started in "Begin" function is done.
  $AsyncWaitHandle$ is used in "End" function if the~"End" function is called 
  and the~operation is still running. 
  \item Flag $CompletedSynchronously$ tells whether  
  $AsyncWaitHandle$ has been used to wait to the~end of the~operation.
  $CompletedSynchronously$ is always set to false if callback is used.
  \item $IsCompleted$ tells whether the~operation from "Begin" function terminated or not.
  \end{itemize}

\subsection*{The~"Begin" and "End" functions} \label{sec:beginend}
  Let us describe public methods of $AsyncNoResult$, 
  which are used to implement "Begin" and "End" functions.
  $IAsyncResult's$ properties are not enough to implement $BeginGetIR$,
  $EndGetFtion$ or any other "Begin" and "End" functions.
  $BeginGetIR$ method uses a constructor of $AsyncNoResult$. 
  It also uses the~$SetAsCompleted$ function 
  and the~$EndInvoke$ function both from $AsyncResult$ subclass.
  We will explain the~interesting and crucial part of both classes. 
  For implementation details see code in Figure~\ref{result} and~\ref{noresult}.
  
  %todo obrazek ISA  $AsyncNoResult$ AsyncResult$ a IAsyncResult$ 
  \begin{remark}
  A constructor of $AsyncNoResult$ only sets the~field members, 
  which are not changing during $AsyncNoResult$ existence.
  The~implementation of $SetAsCompleted(..)$ method 
  from $AsyncNoResult$ raises an exception to $AsyncNoResult$.
  The~function $SetAsCompleted(..)$ from $AsyncResult$ overloads $SetAsCompleted(..)$ method
  from its base class $AsyncNoResult$ and adds 
  a~possibility to set the~results instead of raising the~exception.
  Third overload is implemented in $AsyncResult$ so that the~$GetPicture(..)$ 
  command can set both exception and the~result at one time.
  $EndInvoke(..)$ is called from "End" function and does all its logic. 
  It checks whether the~called operation has finished.
  If the~operation is still pending, it sets up a new $AsyncWaitHandle$
  and waits to its termination. At the~end it throws an exception if one has been set up, 
  or it returns a result if $EndInvoke(..)$ from $AsyncResult$ was called.
  \end{remark}

\begin{figure}[!hbp]	
\begin{lstlisting}[language=cs]
public class AsyncResultNoResult : IAsyncResult {
  // Fields set at construction which never change 
  readonly AsyncCallback m_AsyncCallback;
  readonly Object m_AsyncState;
  // Fields which do change after operation completes
  const Int32 c_sp = 0;//StatePending
  const Int32 c_scs= 1;// StateCompletedSynchronously
  const Int32 c_sca = 2;//StateCompletedAsynchronously
  Int32 m_CompletedState = c_sp;
  // Field that may or may not get set depending on usage
  ManualResetEvent m_AsyncWaitHandle;
  // Fields set when operation completes
  Exception m_exception;
  // Name makes debugging easier in Elib. It shows, which command was used.
  string name;
  public string Name { 
    get { return (name != null) ? name : ""; } 
    set { name = value; 		} 
  }
  public AsyncResultNoResult(AsyncCallback asyncCallback, Object state, string name_) {
    m_AsyncCallback = asyncCallback;
    m_AsyncState = state;
    name = name_;
  }
  public AsyncResultNoResult(AsyncCallback asyncCallback, Object state) : 
    this(asyncCallback, state, null) { }
  public void SetAsCompleted(Exception exception, Boolean completedSynchronously) {
    // Passing null for exception means no error occurred. 
    // This is the~common case
    m_exception = exception;
    // The~m_CompletedState field MUST be set prior calling the~callback
    Int32 prevState = Interlocked.Exchange(ref m_CompletedState, 
      completedSynchronously ? c_scs : c_sca);
    if (prevState != c_sp)
      throw new InvalidOperationException("You can set a result only once");
    // If the~event exists, set it
    if (m_AsyncWaitHandle != null) m_AsyncWaitHandle.Set();
    // If a callback method was set, call it
    if (m_AsyncCallback != null) m_AsyncCallback(this);
  }
\end{lstlisting}
\caption{$AsyncNoResult's$ members and constructors} 
\label{noresult}
\end{figure}



\begin{figure}[!hbp]	
\begin{lstlisting}[language=cs]
  public void EndInvoke() {
    // This method assumes that only 1 thread calls EndInvoke 
    // for this object
    if (!IsCompleted) {
      // If the~operation isn't done, wait for it
      AsyncWaitHandle.WaitOne();
      AsyncWaitHandle.Close();
      m_AsyncWaitHandle = null;  // Allow early GC
    }      
    // Operation is done: if an exception occured, throw it
    if (m_exception != null) throw m_exception;
  }

  //region Implementation of IAsyncResult
  public Object AsyncState { get { return m_AsyncState; } }
  public Boolean CompletedSynchronously{get { 
    return Thread.VolatileRead(ref m_CompletedState) ==  ic_scs; }}
  public WaitHandle AsyncWaitHandle {
    get {
      if (m_AsyncWaitHandle == null) {
        Boolean done = IsCompleted;
        ManualResetEvent mre = new ManualResetEvent(done);
        if (Interlocked.CompareExchange(ref m_AsyncWaitHandle,
           mre, null) != null) {
          // Another thread created this object's event; dispose 
          // the~event we just created
          mre.Close();
        } else {
          if (!done && IsCompleted) {
            // If the~operation wasn't done when we created 
            // the~event but now it is done, set the~event
            m_AsyncWaitHandle.Set();
          }
        }
      }
      return m_AsyncWaitHandle;
    }
  }
  public Boolean IsCompleted {
    get {return Thread.VolatileRead(ref m_CompletedState) != c_sp; }}
  //endregion Implementation of IAsyncResult
}
\end{lstlisting}
\caption{$AsyncNoResult$ internals} 
\label{noresulti}
\end{figure}


  An important feature of $AsyncNoResult$, which is inherited by $AsyncResult$, is the~creation of an $EventWaitHandle's$ instance.
  It is not created in all cases and it is created at most once during an $AsyncNoResult's$ life cycle.
  An instance of $EventWaintHandle$ is created only if the~user explicitly called get method for $WaitHandle$ or
  if the~$EndInvoke$ method was called and the~operation is still pending.
  It means that if you use callback and do not call "End" function then no instance of $EventWaitHandle$ is created.
  Let us stress that $EventWaitHandle$ is provided from an operating system and its instantiation is relatively slow.

  The~$name$ field seems useless, but it allows "Begin" function to put its name in it. 
  The~name can be used in logging or debugging, 
  which will be described in following paragraphs devoted 
  to design of "Begin" and "End" functions.

  Let us note that $AsyncResult$ adds no crucial logic except setting 
  a~result in $SetAsCompleted$ function and
  returning the~result in $EndInvoke$ function. 
  $AsyncResult$ uses its base class $AsyncNoResult$ to implement the~logic.
\begin{figure}[!hbp]
\begin{lstlisting}
public class AsyncResult<TResult> : AsyncResultNoResult {
  // Field set when operation completes
  TResult m_result = default(TResult);
  public AsyncResult(AsyncCallback asyncCallback, Object state,string name) : 
    base(asyncCallback, state,name) { }
  public AsyncResult(AsyncCallback asyncCallback, Object state) : 
    this(asyncCallback, state, null) { }
  //enable to set Result. AsyncNoResult enables to set exception.
  public void SetAsCompleted(TResult result, Boolean completedSynchronously) {
    // Save the asynchronous operation's result
    m_result = result;
    // Tell the base class that the operation completed 
    // sucessfully (no exception)
    base.SetAsCompleted(null, completedSynchronously);
  }
  // Allows to set both the exception and the result. Added for GetImage(..).
  public void SetAsCompleted(TResult result, Boolean completedSynchronously, Exception exception) {
    m_result = result;
    base.SetAsCompleted(exception, completedSynchronously);
  }
  new public TResult EndInvoke() {
    base.EndInvoke();// Wait until operation has completed 
    return m_result; // Return the result (if above didn't throw)
  }
}
\end{lstlisting}
\caption{$AsyncResult<T>$} \label{result}
\end{figure}
  \subsection*{Implementation of "Begin" and "End" functions} 
  The "Begin" and "End functions are the~key functions of the~$IAsyncResult$ implementation.
  All the~"Begin" and "End" functions' implementations are similar. 
  They are implemented similarly to functions $BeginGetIR's$
  and $EndGetFtion's$ from Section~\ref{arexample}.
  The~implementation of $BeginGetIR's$ and its "End" function is shown in Figure~\ref{beginsens}.
  All "Begin" functions use $Epuck's$ interface with the~$Okf$ and $Kof$ callbacks introduced
  in Section~\ref{sec:approach}.	

\begin{figure}[!hbp]
\begin{lstlisting}
public IAsyncResult BeginGetIR(double timeout, AsyncCallback callback, object state) {
  AsyncResult<int[]> a = 
  new AsyncResult<int[]>(callback, state, logFunctionNames["BeginGetIR(..)"]);
  GetIR(receivedSensors<int[]>, failed, a, timeout);
  return a;
}
static T EndSensors<T>(IAsyncResult ar) {
  AsyncResult<T> a = (AsyncResult<T>)ar;
  return a.EndInvoke();
}
public int[] EndGetFtion(IAsyncResult ar) { 
  return EndSensors<int[]>(ar); 
}
\end{lstlisting}	
\caption{An example of "Begin" and "End" function for sensors.}
\label{beginsens}
\end{figure}

  The~"Begin" function creates an instance $a$ of the~class $AsyncNoResult$ respectively an $AsyncResult$ instance. 
  The~function passes the~supplied callback with its $state$ object to
  $a$. Third argument of $a's$ constructor is a name of the~used function.

  In Figure \ref{beginsens}  $BeginGetIR(..)$ instantiates $AsyncResult<int[]>$, because $BeginGetIR(..)$
  expect array of $ints$ as its answer. 
  The~$Name$ field of $AsyncResult$ is filled with the~$string$ value from $logFunctionNames$ dictionary. 
  The~dictionary values are by default set to their key values, so
  the~$Name$ in $BeginGetIR(..)$ function is filled with "BeginGetIR(..)" value.
  The~$a$ instance is passed as the~$state$ argument and is at disposal to the~$failed(..)$ and 
  $receiveSensors(..)$ functions.
  The~function $receiveSensors(..)$ is called with generic parameter $int[]$, 
  because the~$GetIR$ values expect an array of $ints$ from sensor.
  Sensor's methods as well as actuator's methods use the~$failed(..)$ function as its $Kof(..)$ callback.
  An exception is the~$GetImg(..)$ function which uses the~$failedBitmap(..)$ callback instead.
  The~last action of each "Begin" function is returning the~instance $a$.
  Functions, which control actuators, call the~$received(..)$ function as the~$Okf(..)$ callback. 
  See an example in Figure~\ref{beginact}.

  Let us shortly introduce the~"End" functions before we will focus on the~$Okf(..)$ and 
  $Kof(..)$ callbacks used in the~"Begin" functions.
  "End" functions have two tasks of the~"End" functions.
  The~first one is to cast the~$IAsyncResult$ argument to the~correct type of $AsyncResult$ 
  or to the~$AsyncNoResult$ class. The~second task is to call the~$EndInvoke(..)$ method.
  If the~"End" function is called with an $IAsyncResult$ argument from a sensor command, 
  the~value of the~sensor is returned from $EndInvoke(..)$. See Figure~\ref{beginsens}. 
  If the~$IAsyncResult$ argument is passed from the~"Begin" function, 
  which controls an actuator, then $EndInvoke(..)$ is called and nothing is returned. See Figure~\ref{beginact}.
  
\begin{figure}[!hbp]
\begin{lstlisting}
public IAsyncResult BeginMotors(double leftMotor, double rightMotor, 
       double timeout, AsyncCallback callback,Object state) {
 AsyncResultNoResult a = 
   new AsyncResultNoResult(callback, state,logFunctionNames["BeginMotors(..)"]);
 Motors(leftMotor, rightMotor, received, failed, a, timeout);
 return a;
}
public void EndActuators(IAsyncResult ar) {
 AsyncResultNoResult a = (AsyncResultNoResult)ar;
 a.EndInvoke();
}
\end{lstlisting}	
\caption{An example of "Begin" and "End" function for actuators.} \label{beginact}
\end{figure}
 
  \subsection{Callback: Alternative to the "End" function} 
  The~callbacks are called after the~delivery of the~answer or after the~$timeout$ expiration.
  The~callback allows to process the~result of the~operation.
  In the~$IAsyncResult$ interface the~results are set via calling the~$SetAsCompleted$ method 
  on the~$AsyncNoResult$ respectively $AsyncResult$ instance.
  If the~operation fails, the~$Kof$ callback $failed$ is called. 
  In the~$failed$ function the~$SetAsCompleted$ method is called 
  and an exception is passed to the~first argument of $SetAsCompleted$ overridden function.
  See the~function $failed$ in Figure~\ref{Ikofs} on the first line.

  The~only $Epuck's$ method that can return both the~exception and the~result is the~$BeginGetPicture(..)$ function.
  The~function $receivedSensors<Bitmap>$ is used in the~$Okf$ delegate $BeginGetPicture(..)$, and 
  the~special function $failedBitmap(..)$ is called if an exception has been raised.
  The~$Kof(..)$ callback raises a special exception, if the~image was captured and has been 
  delivered after timeout expiration.
  Its implementation is shown in Figure~\ref{Ikofs}. 

  
\begin{figure}[!hbp]
\begin{lstlisting}
static void failed(object asyncNoResult) {
  AsyncResultNoResult ar = (AsyncResultNoResult)asyncNoResult;
  ar.SetAsCompleted(new ElibException(ar.Name + " command hasn't been confirmed in timeout"), false); 
}
static void failedBitmap(Bitmap pic,object asyncResult) {
  if (pic != null) {
    AsyncResult<Bitmap> ar = (AsyncResult<Bitmap>)asyncResult;        
    ar.SetAsCompleted(pic, false, new ElibException(ar.Name + 
      " command GetPicture has not been confirmed in timeout, but picture is still available in AsyncResult<Bitmap>"));
  } else
    failed(asyncResult);
}
\end{lstlisting}	
\caption{$Kof$ callbacks for $IAsyncResult$} \label{Ikofs}
\end{figure}


  If the~answer is delivered in time, then the~$Okf$ callback is called.
  The~sensor's callback $receivedSensors<T>$ passes the~answer of the~type $T$ to its first argument.
  The~actuators callback $received$ just passes $null$ to its first argument, which indicates
  no exception was raised.
  See the~code below in Figure~\ref{Iokfs}.


\begin{figure}[!hbp]
\begin{lstlisting}
static void received(object asyncNoResult) {
  AsyncResultNoResult ar = (AsyncResultNoResult)asyncNoResult; ar.SetAsCompleted(null, false); 
}
static void receivedSensors<T>(T b, object asyncResIntArr) {
  AsyncResult<T> a = (AsyncResult<T>)asyncResIntArr;
  a.SetAsCompleted(b, false);
}
\end{lstlisting}	
\caption{$Okf$ callbacks for $IAsyncResult$} \label{Iokfs}
\end{figure}

\section{A summary of Elib interfaces}
\label{sec:suminterface}
  In the previous three subsections the~implementations of the~two interfaces of $Epuck$ 
  and one $Sercom's$ interface have been described.

  $IAsyncResult$ is built on the~basic $Epuck's$ interface with the~typed $Okf(..)$ and $Kof(..)$ callbacks. 
  The~basic $Epuck$ interface is itself built on $Sercom's$ $Okf$ / $Kof$ interface.
%  The~purpose of the~interfaces is to make programming e-Puck over Bluetooth easier.
  The~$IAsyncResult$ is the~most comfortable of the~three interfaces. 
  The~use of $Sercom's$ interface needs good knowledge of BTCom protocol and 
  it forces user to process every answer of {\it BTCom}.

  Let us compare the~possibilities and limitations of the~interfaces against each other.
  The~$Sercom's$ interface and $Epuck$ basic interface with $Okf$ and $Kof$ 
  have the~same limitations and possibilities for the~e-Puck running {\it BTCom} version 1.1.3. 
  
  Every program written using $Epuck's$ basic interface can be written
  in $Sercom$ by implementing $Epuck's$ interface as it is in {\it Elib}.
  On the~other hand, every program that uses $Sercom$ interface and communicates with {\it BTCom}
  version 1.1.3 on e-Puck, can be written using $Epuck's$ basic interface. 
  $Epuck's$ basic interface is a specialization of $Sercom$ for concrete version of {\it BTCom}
  protocol.

%%%%todo vyjasnit a vysvetlit, ze jde simulovat kof pomoci IAsyncResult
  $IAsyncResult$ limits the~role of the~$Kof$ callback, but does not limit the~role of the~$Okf(..)$ callback.
  If a user wants to implement an $Okf$ logic using the~$IAsyncResult$ interface, he uses callback from $IAsyncResult$
  interface that is passed to the~"Begin" function.
  The~callback is called after the~$received$ respectively $receivedSensor<T>(..)$ function  call 
  the~$SetAsCompleted(..)$ method on an instance $a$ of $IAsyncResult$. 
  Remind the~implementation in Figure~\ref{Iokfs}.
  The~$received(..)$ and $receivedSensor<T>(..)$ functions are called as the~$Okf$ callbacks
  from the~$Epuck's$ basic interface.
  See Figure~\ref{beginact} and Figure~\ref{beginsens} for the~confirmation.
  To conclude the~$IAsyncResult$ callback is invoked in the~$Okf(..)$ callback of $Epuck's$ basic interface.

\begin{figure}[!hbp]
\begin{lstlisting}
static void SimulatingKof_over_IAsResult(Epuck ada) {
  //the timeout is too small!
  ada.BeginGetImage(0.001, okf, ada);
}
\end{lstlisting}
\caption{Start of the~behaviour.}
\label{c:start}
\end{figure}

  The~limitation of $IAsyncResult$ arises from setting an exception in the~$Kof(..)$ callbacks,
  which are used in the~$IAsyncResult's$ implementation.
  The only difference is, that the~functions in Figures~\ref{c:start} 
  and~\ref{c:okfsim} use the~$kof(..)$ callback function
  from Figure~\ref{iasynckof} 
  which implements the~$Kof$ logic in spite of the~functions use $IAsyncResult$ interface.

  The~$Kof$ logic should be implemented if an exception is raised. 
  The~exception is raised in callback passed to $IAsyncResult$ if the~answer is not delivered in timeout. 
  The~nearest place, where it can be caught is in the~call of the~$EndInvoke$ method.
  The~called $EndInvoke$ method is associated with the~$IAsyncResult$ instance. 
  The~common way for a user to invoke the~$EndInvoke$ method is to call the~"End" method 
  on the~instance of $Epuck$ with the~$IAsyncResult$ object as its parameter. 
  This technique is used in Figure~\ref{c:okfsim}.
  The~call of $ada.EndGetImage(ar\_)$ gets the~image and the~callback function continues
  or the~$EndGetImage(..)$ function throws an exception which is caught by $try-catch$ block.
  In $catch$ block the~user defined $kof$ function is invoked.
  
\begin{figure}[!hbp]
\begin{lstlisting}
//It can be only a callback of BeginGetImage,
//because the ar paramater has to contain a Bitmap
//See 8. row!
static void okf(IAsyncResult ar_) {
  if (!endf) {
    Epuck ada = (Epuck)ar_.AsyncState;
    try{
      Bitmap b = ada.EndGetImage(ar_);//no EventWaitHandle created
      IAsyncResult ar = ada.BeginMotors(-1, 1, 0.1, null, null);// some work
      //simulate image processig
      Thread.Sleep(20);
      ada.EndFtion(ar);
      //the timeout is too small!
      ada.BeginGetImage(0.01, okf, ada);
    } catch (ElibException) {
      //has to be fixed in kof
      ada.BeginStop(0.1, kof, ada);
    }
  } else
    endconfirmed.Set();
}
\end{lstlisting}
\caption{The~$Okf$ callback with too small timeout.}
\label{c:okfsim}
\end{figure}

  The~logic of the~$Kof(..)$ function from the~basic $Epuck's$ interface is preserved, because the~user-defined
  $kof(..)$ is called in the~same case when the~$Kof(..)$ is called. Both are invoked if the~$timeout$ expires.
  On the~other hand, the~$kof(..)$ uses an extra command to be invoked. In Figure~\ref{c:okfsim} it
  is $ada.BeginStop(..)$ command, which invokes $okf(..)$. The~$Stop(..)$ function would be the~first command
  in $Kof(..)$ logic implementation of $Epuck's$ basic interface.
  The~second difference is that the~same $Kof(..)$ callback is called from $EndGetImage(..)$ and from the
  commands in the~body. In this example the~same $kof(..)$ is called for $EndGetImage(..)$ and 
  for $EndActuators(..)$, which is the~pair function of the~$BeginMotors(..)$ 
  command from the~body of the~$okf(..)$ function.
  The~exception's origin can be found out from the~$message$ property of the~exception, 
  where the~$Name$ property of the~$AsyncNoResult$ instance is used.

  \subsubsection*{Summary} % (fold)
  The~unknown source of an~exception as well as the~extra invocation command are minor problems, because
  there is usually single $Kof(..)$ callback that consists of more than one command. 
  Therefore, $IAsyncResult$ interface of $Epuck$ class can be considered as powerful as $Epuck's$ basic interface.

  \begin{remark} The~lost answer usually completely breaks the~logic of $Okf$
  implementation. If it happens, the~appropriate solution is to put e-Puck into
  the~starting position of the~behaviour. Usually, commands to stop e-Puck are
  sent and a message is sent to the~user or to the~log file. See Figure
 ~\ref{iasynckof}. \end{remark}

\begin{figure}[!hbp]
\begin{lstlisting}
//It can be called from any function,
//because we call only EndFtion!
//It can be applied to every IAsyncResult in Elib.
//See 7. row!
static void kof(IAsyncResult ar_) {
  if (!endf) {
    Epuck ada = (Epuck)ar_.AsyncState;
    ada.EndFtion(ar_);
    try {
      IAsyncResult ar = ada.BeginStop(to, null, null);//do the repair actions
      ada.EndFtion(ar);
      Console.WriteLine("The~problem is fixed. Lets call okf!");
      ada.BeginGetImage(0.1, okf, ada);
    } catch (ElibException) {
      ada.BeginStop(0.1, kof, ada);
    }
  } else
    endconfirmed.Set();
}
\end{lstlisting}
\caption{Simulation of $Kof$ using $IAsyncResult$}
\label{iasynckof}
\end{figure}
%  We have concluded that the~$Sercom$ interface, the~$Epuck's$ basic interface and 
%  the~$IAsyncResult$ interface have equal power for implementing algorithms.

  \subsection*{Demands of $Epuck$ and $Sercom$ class on operating system} 
  Let us explore the~demands and the~load of operating system (OS) when we use these interfaces.
  The~more sophisticated the~interface is, the~bigger demands on OS it has.
  It is a consequence of building one interface upon the~other.
  Let us stress that every program written using $IAsyncResult$ interface, 
  can be written with less or equal system resources using $Sercom's$
  interface. On the~other hand, the~programmers, 
  who use more complicated interface, for example the~$Sercom$ class, do not usually find better way 
  than the~one that is designed by the~richer interface like $IAsyncResult$.

  In fact, $IAsyncResult$ is not much more demanding than $Sercom$ interface, if it is not misused.
  The~only field, where $IAsyncResult$ does not keep up with $Sercom's$ interface, 
  is an extremely frequent calling of $Kof$ callbacks.
  $IAsyncResult$ throw an exception for every $Kof$ callback invocation, 
  whereas $Sercom's$ interface just needs to invoke a callback.
  $IAsyncResult$ also needs to call other functions, but this is quite fast. 
  The~raising and catching an exception is significantly slower.
  On the~other hand, such behaviour that extensively uses $Kof$ callbacks 
  has very special purpose or is a bad programming style.
  See Chapter~\ref{chap:usage} for guidelines how to use the~interfaces.

  The~only resource, which can be extensively used in $IAsyncResult$, is $EventWaitHandle$. 
  $EventWaitHadndle$ is a synchronisation primitive provided
  by OS. There is at most one $EventWaitHandle$ created for each instance of $IAsyncResult$ in {\it Elib}. 
  On the~other hand, by using callbacks in {\it Elib's} $IAsyncResult$
  implementation, the~creation of $EventWaitHandles$ is completely avoided.

  Let us note that $Sercom's$ and the~simple $Epuck's$ interface 
  are almost identical and therefore they have almost identical performance.
  The~$Epuck$ class adds answers processing and allows logging. 
  The~user would do the~processing of the~answers anyway.
  If the~logging is off, the~one additional "if statement" in method adds no overhead. 
  Preferring one interface over another in {\it Elib} does not significantly influence the~performance of application.

  \begin{remark}
   Let us remind, that we use $Threadpool$ for callbacks, so each callback
   does not start new thread.
   The $Threadpool$ distributes the free threads to functions.
  \end{remark}
  We have tested the performance of {\it Elib}. Let us introduce 
  the~results and parameters of $Elib$ library.
  The~size of the~compiled {\it Elib} library is less 50 KB.
  Using $IAsyncResult$ in "Bull" behaviour  {\it TestElib} consumes 8512 KB of memory.
  Compare it with a simple console application, which needs 4580 KB of memory, or with Google Chrome, 
  %todo compare with webots todo FEro
  which consumes more than 30000 KB of memory.
  %todo reference
  During three performance tests of $SimulatingKof\_over\_IAsResult(..)$,
  the~number of threads of the~{\it TestElib} application did not exceed 10. 
  See Section~\ref{iasynckof}. Moreover, the~threads were usually unused
  in $ThreadPool$ system class which has used only one or two. 
  The~two worker threads were running of course all the~time.
   %csReadLineEmpty.exe 4580KB csReadLineEmpty.vshost.exe 15184KB
   %{\it TestElib }.vshost.exe consumed 14108KB

  The~Table~\ref{times1}  was obtained from measuring using the~$ConsoleTestSensorsTimeout$ and
  $ConsoleTestActuatorsTimeout$ functions with $timeout$ 10 seconds.
  It shows that most of commands were delivered under 0.1 seconds. 
  On the contrary, the~commands to take a picture or to set camera parameters 
   lasted almost half a second. 
  The~reason is that the~camera is very demanding device and it produces a lot of data.
  The~special commands for calibrating IR sensors and for resetting e-Puck lasted even longer.
  The~"reset" command has even exceeded the~$timeout$,
  which means that part of its answer was lost.

  The~values in the~table were measured from 10 independent measurements split into two tests. 
  The first test consists of the first six measurements which used intentionally e-Puck with
  a~not fully charged battery. The second test comprises another 4 measurements performed
  on~e-Puck with a~recharged battery.
  The~first six measurements used e-Puck with a not fully charged battery.
  The last four tests were performed on e-Puck with a recharged battery.

%1-3 neprazdna baterie debug
%4-6 not empty baterry, release 
%6-9 fully charge baterry, release 
%9-12 fully charge baterry, debug

\begin{table}[!hbp]
\begin{tabular}{lcccccc}
Command string & {\tiny Average (1. test)}  & {\tiny Variance (1. test)}& {\tiny Average (2. test)} & {\tiny Variance (2. test)}\\
GetHelpInfo(..)& 0.13873 & 0.00036& 0.12162&0.00007\\
GetAccelerometer(..)&0.07017&0.00009&  0.06393&0.00009\\ 
GetVersionInfo(..)&0.04153&0.00028&.05715&0.00055\\ 
GetCamParams(..)&0.04927&0.00001&  0.05073&0\\ 
GetEncoders(..)&0.0481&0.00012&  0.04015&0.00026\\ 
GetImage(..)&0.30715 &0.00118& 0.31232&0.00698\\ 
GetIR(..)&0.06543 &0.00011&0.05977&0.00008\\ 
GetIRInfo(..)&0.06002 &0.00055& 0.05053&0.00088\\
GetLight(..)&0.08305 &0.00083&0.0919&0.00106\\
Microphones(..)& 0.0319&0.00045 & 0.01868&0\\
ada.GetSelector(..)& 0.07517&0.00296& 0.04993& 0\\
GetSpeed(..)& 0.01298&0.00066&   0.00245&0.00001\\
Reset(..) &{\it 1.3942} & 0 &{\it 1.39023} &0.00007 \\
BodyLight(..)& 0.03253&0.00009&   0.03057&0.00004\\
CalibrateIRSensors(..)&3.69635&0.00006&3.69173&0.00013\\
FrontLight(..)&0.03123&0.00002 & 0.02998&0.00004\\
LightX(..)& 0.02515&0.00015&  0.02347&0.00012\\
Motors(..)&0.03432&0.00029&  0.0252&0.00015\\
PlaySound(..)& 0.04403& 0.00017&  0.03488&0.00032\\
SetCam(..)& 0.16965& 0.00028& 0.16708&0.00026\\
SetEncoders(..)& 0.04013&0.00051& 0.03243&0.00021\\
Stop(..)&0.02375&0.00004&  0.0265&0.00017\\
\end{tabular}
\caption{Times between sending commands and receiving their answers}
\label{times1}
\end{table}

